home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 5 / Apprentice-Release5.iso / Source Code / C / Applications / GW AdaEd 1.4.2 / GWAdaDemos / NYUDemos / PAGER2.DOC < prev    next >
Text File  |  1993-01-31  |  14KB  |  478 lines
  1.                                      PAGER2
  2.  
  3.                                 by Richard Conn
  4.  
  5.                   PAGER2 is   a  tool  for  creating  paged  files,
  6.              extracting  the component files from a paged file, and
  7.              scanning  paged  files,   where   a  paged  file  is a
  8.              file  composed  of  one  or  more  files  prefixed  by
  9.              banners.    PAGER2   is  based  in  concept   on   the
  10.              UNPAGE   tool submitted to the Ada Software Repository
  11.              on SIMTEL20 by Mitre Corporation.  
  12.  
  13.                   Paged files   are   convenient   mechanisms   for
  14.              storing  related   files.   They   reduce   cluttering
  15.              in   the  directories  and  simplify the file transfer
  16.              process  by requiring  the  user  to transfer only one
  17.              file  in  order  to  obtain  all  files pertinent to a
  18.              particular  project  or  tool.   Additionally,   paged
  19.              files   are  text  files  which  can  be  handled more
  20.              readily  than  the 8-bit binary images associated with
  21.              other   file   grouping   mechanisms  (see   the  file
  22.              OILBR.DOC     in   the   directory   PD2:<ADA.GENERAL>
  23.              in   the   Ada  Software Repository).  Paged files may
  24.              be  manipulated  by  a  text  editor  if necessary.  
  25.  
  26.                   For these   reasons,   paged   files   have  been
  27.              adopted   as   a   standard  for  file  storage in the
  28.              Ada  Software Repository.  The file type of SRC (as in
  29.              MYFILE.SRC) indicates that a file is paged.  
  30.  
  31.  
  32.  
  33.  
  34.           1.  PAGED FILE FORMAT 
  35.  
  36.                A paged  file  is  a file composed of one or more files
  37.           prefixed  by banners of the form: 
  38.  
  39.                           ::::::::::
  40.                           filename
  41.                           ::::::::::
  42.           or
  43.                           --::::::::::
  44.                           --filename
  45.                           --::::::::::
  46.  
  47.                The first   banner   conforms   to  the  PAGE  standard
  48.           employed  on  UNIX.  The  second  banner is an adaptation of
  49.           the  first  form  which  resembles Ada comments.  The second
  50.           banner  is  convenient   when   the   paged   file  contains
  51.           several   files   associated  with  a particular Ada program
  52.           and  they  are  placed  in  the  paged  file  in compilation
  53.  
  54.  
  55.           Richard Conn                                          Page 1
  56.  
  57.  
  58.                                      PAGER2
  59.  
  60.  
  61.           order.   The  resulting  paged  file  may  then  be compiled
  62.           without being disassembled first.  
  63.  
  64.  
  65.  
  66.  
  67.           2.  PAGER2 COMMANDS 
  68.  
  69.                PAGER2 responds to the following commands: 
  70.  
  71.                 1.  PAGE or P - create a paged file 
  72.  
  73.                 2.  UNPAGE  or U - extract the components of a
  74.                   paged file into their separate files 
  75.  
  76.                 3.  LIST  or  L  -  list components of a paged
  77.                   file to the screen 
  78.  
  79.                 4.  INCLUDE  or I - list components of a paged
  80.                   file into an include file 
  81.  
  82.                 5.  HELP or H - print a command summary 
  83.  
  84.                 6.  EXIT or X - exit PAGER2 
  85.  
  86.                The case  used  to  enter  these  command  verbs is not
  87.           significant.    The  case  used  to  enter  the  file  names
  88.           referenced  as arguments to the command verbs is significant
  89.           if  the  host  operating  system  distinguishes case in file
  90.           names, as does UNIX (but not MSDOS).  
  91.  
  92.  
  93.           2.1.  PAGE Command 
  94.  
  95.                The PAGE  function  is  used  to  created a paged  file
  96.           from   one  or more component files.  The syntax of the PAGE
  97.           command is: 
  98.  
  99.                PAGE [filename | @include_filename]+ paged_file_name
  100.  
  101.                Two or  more file names may be specified after the PAGE
  102.           verb.   The  last file name is the name of the paged file to
  103.           be  created.  The other file names are the names of files to
  104.           be  placed into the paged file or the names of include files
  105.           from  which  the  names of files to be placed into the paged
  106.           file are to be extracted.  
  107.  
  108.                If the  user prefixes the name of a component file with
  109.           an   atsign  character  (@), the indicated file is processed
  110.           as  an  include  file.   An  include  file  is  a file which
  111.           contains   the   names  of  zero  or  more component  files,
  112.           one   name   per  line  starting in the first column.  Other
  113.  
  114.  
  115.           Richard Conn                                          Page 2
  116.  
  117.  
  118.                                      PAGER2
  119.  
  120.  
  121.           include  files  may   be   referenced   within   an  include
  122.           file    by   prefixing   their   names   with   the   atsign
  123.           character.   Comments  may  be placed within an include file
  124.           by  placing  two  dashes  in  the   first   two columns of a
  125.           line.  The following is an example of an include file: 
  126.  
  127.                    Example                      Comments
  128.                    =======                      ========
  129.           --
  130.           -- This is an include file for        Comment at the beginning
  131.           --  my favorite tool
  132.           --
  133.                                                 Blank lines are allowed
  134.           --
  135.           -- The following include file
  136.           --  contains the names of the         Another comment
  137.           --  Ada source files in compilation
  138.           --  order
  139.           --
  140.           @mytool.cmp
  141.           --
  142.           -- The following are the documentation
  143.           --  files
  144.           --
  145.           mytool.ref
  146.           mytool.doc
  147.           mytool.idx
  148.  
  149.                A single  letter  "P"  may be used rather than the full
  150.           "PAGE"  verb.   An  example  of  the  execution  of the PAGE
  151.           command is: 
  152.  
  153.           PAGER2> page
  154.            PAGE Command requires the name of the paged file and include file
  155.              Syntax: page [@include_file_name|file_name]+ paged_file_name
  156.           PAGER2> p @demo.inc demo.src
  157.            Adding demo.inc -- 8 Lines
  158.            Adding demo1.txt -- 1 Lines
  159.            Adding demo2.txt -- 1 Lines
  160.  
  161.  
  162.           2.2.  UNPAGE Command 
  163.  
  164.                The UNPAGE  function  extracts  the   components   from
  165.           the   indicated  paged   file,  leaving  the  original paged
  166.           file intact.  The syntax of UNPAGE is: 
  167.  
  168.               UNPAGE paged_filename
  169.  
  170.                The single  letter "U" may be used rather than the full
  171.           "UNPAGE"  verb.   An  example of the execution of the UNPAGE
  172.           command is: 
  173.  
  174.  
  175.           Richard Conn                                          Page 3
  176.  
  177.  
  178.                                      PAGER2
  179.  
  180.  
  181.           PAGER2> unpage
  182.            UNPAGE Command requires the name of a paged file
  183.              Syntax: unpage paged_file_name
  184.           PAGER2> u demo.src
  185.            Extracting demo.inc -- 8 Lines
  186.            Extracting demo1.txt -- 1 Lines
  187.            Extracting demo2.txt -- 1 Lines
  188.  
  189.  
  190.           2.3.  LIST Command 
  191.  
  192.                The LIST  function  is  used  to  create  a  text  file
  193.           containing   the  names   of   the  component files within a
  194.           paged file.  The syntax of the LIST command is: 
  195.  
  196.                LIST paged_file_name
  197.  
  198.                The single  letter "L" may be used rather than the full
  199.           "LIST"  verb.   An  example  of  the  execution  of the LIST
  200.           command is: 
  201.  
  202.           PAGER2> list
  203.            LIST Command requires the name of a paged file
  204.              Syntax: list paged_file_name
  205.           PAGER2> list demo.src
  206.            demo.inc -- 8 Lines
  207.            demo1.txt -- 1 Lines
  208.            demo2.txt -- 1 Lines
  209.  
  210.  
  211.           2.4.  INCLUDE Command 
  212.  
  213.                The INCLUDE  command  performs the same function of the
  214.           LIST  command, but it places the output into an include file
  215.           which  is  suitable  for  building  a  new  paged file.  Its
  216.           syntax is: 
  217.  
  218.               INCLUDE paged_file_name include_file_name
  219.  
  220.                The single  letter "I" may be used rather than the full
  221.           "INCLUDE"  verb.  An example of the execution of the INCLUDE
  222.           command is: 
  223.  
  224.           PAGER2> include
  225.            INCLUDE Command requires the name of a paged file
  226.              Syntax: include paged_file_name output_include_file
  227.           PAGER2> include demo.src demo2.inc
  228.            demo.inc -- 8 Lines
  229.            demo1.txt -- 1 Lines
  230.            demo2.txt -- 1 Lines
  231.  
  232.  
  233.  
  234.  
  235.           Richard Conn                                          Page 4
  236.  
  237.  
  238.                                      PAGER2
  239.  
  240.  
  241.           2.5.  HELP Command 
  242.  
  243.                The HELP  command  displays  a brief help text  to  the
  244.           user.   The syntax of this command is: 
  245.  
  246.               HELP
  247.  
  248.                The single  letter "H" may be used rather than the full
  249.           "HELP" verb.  
  250.  
  251.  
  252.           2.6.  EXIT Command 
  253.  
  254.                The EXIT command exits PAGER.  Its syntax is: 
  255.  
  256.               EXIT
  257.  
  258.                The single  letter "X" may be used rather than the full
  259.           "EXIT" verb.  
  260.  
  261.  
  262.  
  263.  
  264.           3.  INVOKING PAGER2 FROM THE COMMAND LINE 
  265.  
  266.                PAGER2 may  also  be  run  from  the command line.  The
  267.           PAGER2  verb  may  be  followed  by  a  conventional  PAGER2
  268.           command,  in  which  case  the  PAGER2 command alone will be
  269.           executed  and  then PAGER2 will exit.  In addition, the verb
  270.           recognized  by  PAGER2 (like HELP or UNPAGE) may be prefixed
  271.           with  a  dash  (-),  making the syntax of the PAGER2 command
  272.           line  similar  to  a  conventional  UNIX  command line.  For
  273.           example,  to  obtain  a  display  of the brief help message,
  274.           either of these commands may be used: 
  275.  
  276.               PAGER2 HELP
  277.               PAGER2 H
  278.               PAGER2 -H
  279.               PAGER2 -help
  280.  
  281.                Likewise, to  create  a  paged file, named MYFILES.SRC,
  282.           from   the   component   files   FILE1.TXT,  FILE2.TXT,  and
  283.           FILE3.TXT, a command like the following could be issued: 
  284.  
  285.               PAGER2 -PAGE FILE1.TXT FILE2.TXT FILE3.TXT MYFILES.SRC
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.           Richard Conn                                          Page 5
  296.  
  297.  
  298.                                      PAGER2
  299.  
  300.  
  301.           4.  SAMPLE SESSION 
  302.  
  303.                The following  is  a  sample  PAGER2  session.   It was
  304.           run  on  a  SUN 3 Model 260 running SunOS 3.5.  
  305.  
  306.           ifsun0/xanadu> ls -l
  307.           total 3
  308.           -rw-r--r--  1 xanadu        166 Jun 16 10:23 demo.inc
  309.           -rw-r--r--  1 xanadu         23 Jun 16 10:23 demo1.txt
  310.           -rw-r--r--  1 xanadu         23 Jun 16 10:23 demo2.txt
  311.  
  312.           ifsun0/xanadu> cat demo.inc
  313.           -- This is a demonstration of the PAGER2 program
  314.  
  315.           -- The include file is named DEMO.INC
  316.           demo.inc
  317.  
  318.           -- The source files are DEMO1.TXT and DEMO2.TXT
  319.           demo1.txt
  320.           demo2.txt
  321.  
  322.           ifsun0/xanadu> cat demo1.txt
  323.           This is file DEMO1.TXT
  324.  
  325.           ifsun0/xanadu> cat demo2.txt
  326.           This is file DEMO2.TXT
  327.  
  328.           ifsun0/xanadu> pager2
  329.           PAGER2, Ada Version 1.1
  330.           Type 'h' for Help
  331.  
  332.           PAGER2> page
  333.            PAGE Command requires the name of the paged file and include file
  334.              Syntax: page [@includefilename|filename]+ pagedfilename
  335.  
  336.           PAGER2> p @demo.inc demo.src
  337.            Adding demo.inc -- 8 Lines
  338.            Adding demo1.txt -- 1 Lines
  339.            Adding demo2.txt -- 1 Lines
  340.  
  341.           PAGER2> list
  342.            LIST Command requires the name of a paged file
  343.              Syntax: list pagedfilename
  344.  
  345.           PAGER2> list demo.src
  346.            demo.inc -- 8 Lines
  347.            demo1.txt -- 1 Lines
  348.            demo2.txt -- 1 Lines
  349.  
  350.           PAGER2> include
  351.            INCLUDE Command requires the name of a paged file
  352.              Syntax: include pagedfilename outputincludefile
  353.  
  354.  
  355.           Richard Conn                                          Page 6
  356.  
  357.  
  358.                                      PAGER2
  359.  
  360.  
  361.  
  362.           PAGER2> include demo.src demo2.inc
  363.            demo.inc -- 8 Lines
  364.            demo1.txt -- 1 Lines
  365.            demo2.txt -- 1 Lines
  366.  
  367.           PAGER2> x
  368.  
  369.           ifsun0/xanadu> cat demo.src
  370.           --::::::::::
  371.           --demo.inc
  372.           --::::::::::
  373.           -- This is a demonstration of the PAGER2 program
  374.  
  375.           -- The include file is named DEMO.INC
  376.           demo.inc
  377.  
  378.           -- The source files are DEMO1.TXT and DEMO2.TXT
  379.           demo1.txt
  380.           demo2.txt
  381.           --::::::::::
  382.           --demo1.txt
  383.           --::::::::::
  384.           This is file DEMO1.TXT
  385.           --::::::::::
  386.           --demo2.txt
  387.           --::::::::::
  388.           This is file DEMO2.TXT
  389.  
  390.           ifsun0/xanadu> cat demo2.inc
  391.           -- Include file for demo.src
  392.           demo.inc
  393.           demo1.txt
  394.           demo2.txt
  395.  
  396.           ifsun0/xanadu> pager2
  397.           PAGER2, Ada Version 1.1
  398.           Type 'h' for Help
  399.  
  400.           PAGER2> u demo.src
  401.            Extracting demo.inc -- 8 Lines
  402.            Extracting demo1.txt -- 1 Lines
  403.            Extracting demo2.txt -- 1 Lines
  404.  
  405.           PAGER2> unpage
  406.            UNPAGE Command requires the name of a paged file
  407.              Syntax: unpage pagedfilename
  408.  
  409.           PAGER2> u demo.src
  410.            Extracting demo.inc -- 8 Lines
  411.            Extracting demo1.txt -- 1 Lines
  412.            Extracting demo2.txt -- 1 Lines
  413.  
  414.  
  415.           Richard Conn                                          Page 7
  416.  
  417.  
  418.                                      PAGER2
  419.  
  420.  
  421.  
  422.           PAGER2> x
  423.           ifsun0/xanadu> ls -l
  424.           total 5
  425.           -rw-r--r--  1 xanadu        166 Jun 16 10:26 demo.inc
  426.           -rw-r--r--  1 xanadu        325 Jun 16 10:25 demo.src
  427.           -rw-r--r--  1 xanadu         23 Jun 16 10:26 demo1.txt
  428.           -rw-r--r--  1 xanadu         58 Jun 16 10:25 demo2.inc
  429.           -rw-r--r--  1 xanadu         23 Jun 16 10:26 demo2.txt
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.           Richard Conn                                          Page 8
  476.  
  477.  
  478.